Inside Macintosh: Macintosh Toolbox Essentials
Previous | Chapter Top | Chapter Contents | Next |
You can use the WaitNextEvent (WaitNextEvent) or GetNextEvent (GetNextEvent) function to retrieve an event from the Event Manager and remove the event from the event stream. To provide greater support for multitasking, however, you should use the WaitNextEvent function instead of GetNextEvent whenever possible. You can use the EventAvail function (EventAvail) to look at an event without removing it from the event stream. You can use the AcceptHighLevelEvent function (AcceptHighLevelEvent) to get additional information associated with a high-level event and GetSpecificHighLevelEvent (GetSpecificHighLevelEvent) to search for a specific high-level event.
The FlushEvents (FlushEvents) function removes all low-level events from the Operating System event queue. In general, your application should not empty the event queue.
You can use the SystemClick function (SystemClick) to route events to desk accessories when necessary. The SystemTask (SystemTask) and SystemEvent (SystemEvent) functions are used by the Event Manager, and your application usually does not need to call these two functions.
You usually use the functions provided by the Toolbox Event Manager to retrieve events from the event stream. Even if you are interested only in the events stored in the Operating System event queue, you can retrieve these events using the Toolbox Event Manager by setting the event mask to mask out all events except keyboard, mouse, and disk-inserted events. However, you can choose to use Operating System Event Manager functions to perform this task.
The Operating System Event Manager provides two functions, GetOSEvent (GetOSEvent) and OSEventAvail (OSEventAvail) , to retrieve events from the Operating System event queue. In most cases, your application will not need to use these two functions.
If your application needs to receive key-up events, you can change the system event mask of your application using the SetEventMask function (SetEventMask) . The GetEvQHdr function (GetEvQHdr) returns a pointer to the header of the Operating System event queue.
You can use the WaitNextEvent function to retrieve events one at a time from the Event Manager.
pascal Boolean WaitNextEvent (EventMask eventMask,
EventRecord *theEvent,
UInt32 sleep,
RgnHandle mouseRgn);
The WaitNextEvent function calls the Operating System Event Manager function SystemEvent to determine whether the event should be handled by the application or the Operating System.
If no events are pending for your application, WaitNextEvent waits for a specified amount of time for an event. (During this time, processing time may be allocated to background processes.) If an event occurs, it is returned through the parameter theEvent , and WaitNextEvent returns a function result of true . If the specified time expires and there are no pending events for your application, WaitNextEvent returns a null event in theEvent and a function result of false .
Before returning an event to your application, WaitNextEvent performs other processing and may intercept the event.
The WaitNextEvent function intercepts Command-Shift-number key sequences and calls the corresponding ' FKEY ' resource to perform the associated action. The Event Manager's processing of Command-Shift-number key sequences with numbers 3 through 9 can be disabled by setting the ScrDmpEnable global variable (a byte) to 0.
The WaitNextEvent function also makes the alarm go off if the alarm is set and the current time is the alarm time. The user sets the alarm using the Alarm Clock desk accessory.
The WaitNextEvent function also calls the SystemTask function (SystemTask) , which gives time to each open desk accessory or device driver to perform any periodic action defined for it. A desk accessory or device driver specifies how often the periodic action should occur, and SystemTask gives time to the desk accessory or device driver at the appropriate interval.
Some high-level events may be fully specified by their event records only, while others may include additional information in an optional buffer. To get any additional information and to find the sender of the event, use the AcceptHighLevelEvent function (AcceptHighLevelEvent) .
If the returned event is a high-level event and your application supports Apple events, use the Apple Event Manager function AEProcessAppleEvent to respond to the Apple event and to get additional information associated with the Apple event.
In System 7, if your application is in the foreground and the user opens a desk accessory or other item from the Apple menu, clicks in the window belonging to another application or desk accessory, or chooses another process from the Application menu, the next event reported to your application by the WaitNextEvent function is a suspend event. After your application is switched out, the Event Manager directs events (other than events your application can receive in the background) to the newly activated process until the user switches back to your application or another application.
In a single-application environment in System 6, and in a multiple- application environment in which the desk accessory is launched in the application's partition (for example, a desk accessory opened by the user from the Apple menu while holding down the Option key), the Event Manager handles events for desk accessories in a slightly different manner.
In these environments, when mouse-up, activate, update, and keyboard events (including keyboard equivalents of menu commands) occur, the Event Manager checks to see whether the active window belongs to a desk accessory and whether the desk accessory can handle the event. If so, it sends the event to the desk accessory and WaitNextEvent returns false to your application. Also note that in these environments, the Event Manager returns true for mouse-down events, regardless of whether the mouse-down event is for a desk accessory or not. For mouse-down events in these situations, if the mouse button was pressed while the cursor was in a desk accessory window (as indicated by the inSystem constant returned by the Window Manager FindWindow function), your application should call the SystemClick function (SystemClick) . The SystemClick function handles mouse-down events as appropriate for desk accessories, including sending your application an activate event to deactivate its front window if the desk accessory window needs to be activated.
To get information about the sender of a high-level event and to retrieve any additional data associated with the high-level event, use the AcceptHighLevelEvent function AcceptHighLevelEvent . For details on how to process an Apple event, see the description of the AEProcessAppleEvent function in Inside Macintosh: Interapplication Communication .
To retrieve an event without removing it from the event stream, use the EventAvail function (EventAvail) .
You can use the EventAvail function to retrieve the next available event from the Event Manager without removing the returned event from your application's event stream.
pascal Boolean EventAvail (EventMask eventMask,
EventRecord *theEvent);
Like WaitNextEvent (WaitNextEvent) , the EventAvail function calls the SystemTask function (SystemTask) to give time to each open desk accessory or device driver to perform any periodic action defined for it. The EventAvail function also makes the alarm go off if the alarm is set and the current time is the alarm time. The user sets the alarm using the Alarm Clock desk accessory.
If EventAvail returns a low-level event from the Operating System event queue, the event will not be accessible later if, in the meantime, the event queue becomes full and the event is discarded from it; however, this is not a common occurrence.
See "The Event Record" for a description of the fields in the event record.
Although you should normally use WaitNextEvent , you can also use the GetNextEvent function to retrieve events one at a time from the Event Manager.
pascal Boolean GetNextEvent (EventMask eventMask,
EventRecord *theEvent);
GetNextEvent returns false as its function result if the event being returned is a null event or if GetNextEvent has intercepted the event; otherwise, GetNextEvent returns true . The GetNextEvent function calls the Operating System Manager function SystemEvent to determine whether the event should be handled by the application or the Operating System.
Like WaitNextEvent (WaitNextEvent) , the GetNextEvent function calls the SystemTask function SystemTask to give time to each open desk accessory or device driver to perform any periodic action defined for it. The GetNextEvent function also makes the alarm go off if the alarm is set and the current time is the alarm time. (The user sets the alarm using the Alarm Clock desk accessory.)
The GetNextEvent function also intercepts Command-Shift-number key sequences and calls the corresponding ' FKEY ' resource to perform the associated action. The Event Manager's processing of Command-Shift-number key sequences with numbers 3 through 9 can be disabled by setting the ScrDmpEnable global variable (a byte) to 0.
For greater support of the multitasking environment, your application should use WaitNextEvent instead of GetNextEvent whenever possible. If your application does call GetNextEvent , it should also call the SystemTask function.
See "The Event Record" for a description of the fields in the event record.
After receiving a high-level event (other than an Apple event), use the AcceptHighLevelEvent function to get any additional information associated with the event.
pascal OSErr AcceptHighLevelEvent (TargetID *sender,
unsigned long *msgRefcon,
void *msgBuff,
unsigned long *msgLen);
When your application receives a high-level event, you can use the AcceptHighLevelEvent function to get additional data associated with the event. The AcceptHighLevelEvent function returns information that identifies the sender of the event and the unique message reference constant of the event.
Your application should allocate memory for any additional data associated with the event, then supply a pointer to the data area and also provide the length in bytes of the data area.
The AcceptHighLevelEvent function may move or purge memory. You should not call this function from within an interrupt, such as in a completion function or VBL task.
The trap macro and routine selector for the AcceptHighLevelEvent function are
_OSDispatch
|
You can use the GetSpecificHighLevelEvent function to select and optionally retrieve a specific high-level event from your application's high-level event queue.
pascal Boolean GetSpecificHighLevelEvent (
GetSpecificFilterUPP aFilter,
void *contextPtr,
OSErr *err);
You can use the GetSpecificHighLevelEvent function to search for a specific high-level event in your application's high-level event queue. You specify a filter function as one of the parameters to GetSpecificHighLevelEvent . The GetSpecificHighLevelEvent function calls your filter function once for every event in your application's high-level event queue, until your filter function returns true or the end of the queue is reached.
The GetSpecificHighLevelEvent function passes the value referenced by the contextPtr parameter to your filter function. Your filter function also receives as parameters the event record associated with the high-level event and the target ID structure that identifies the sender of the event. Your filter function can compare the value referenced by the contextPtr parameter with any of the other information it receives.
If your filter function finds a match, it can call AcceptHighLevelEvent (AcceptHighLevelEvent) if necessary, and then return true . If your filter function does not find a match, then it should return false .
If your filter function returns true , the GetSpecificHighLevelEvent function returns true . If your filter function returns false for all high-level events in your application's event queue, or if there are no high-level events in the queue, GetSpecificHighLevelEvent returns false .
The GetSpecificHighLevelEvent function may move or purge memory. You should not call this function from within an interrupt, such as in a completion routine or VBL task.
The trap macro and routine selector for the GetSpecificHighLevelEvent function are
_OSDispatch
|
See "Filter Function for Searching the High-Level Event Queue" for more information about how to define a filter function and the parameters that GetSpecificHighLevelEvent passes to your filter function.
The FlushEvents function removes low-level events from the Operating System event queue. Note that FlushEvents does not remove any types of events not stored in the Operating System event queue.
You can choose to use the FlushEvents function when your application first starts to empty the Operating System event queue of any keystrokes or mouse events generated by the user while the Finder loaded your application. In general, however, your application should not empty the queue at any other time as this loses user actions and makes your application and the computer appear unresponsive to the user.
pascal void FlushEvents (EventMask whichMask, EventMask stopMask);
FlushEvents removes only low-level events stored in the Operating System event queue; it does not remove activate, update, operating-system, or high-level events.
You specify which low-level events to remove using the whichMask and stopMask parameters. FlushEvents removes the low-level events specified by the whichMask parameter, up to but not including the first event of any type specified by the stopMask parameter.
If the event queue doesn't contain any of the events specified by the whichMask parameter, FlushEvents does not remove any events from the queue.
You must set up register D0 with the event mask ( whichMask ) and stop mask before calling FlushEvents . When FlushEvents returns, register D0 contains 0 if all events were removed from the queue or, if all events were not removed from the queue, an event code that specifies the type of event that caused the removal process to stop.
|
0 if all events were removed from the queue, or the event code of the event that stopped the search (low-order word) |
|
After receiving a mouse-down event, your application should call the Window Manager function FindWindow (FindWindow) to determine where the cursor was when the mouse button was pressed. If FindWindow returns the inSysWindow constant, call the SystemClick function to handle the event.
pascal void SystemClick (const EventRecord *theEvent,
WindowPtr theWindow);
If a mouse-down event occurred in a desk accessory's window, the SystemClick function determines which part of the desk accessory's window the cursor was in when the mouse button was pressed and routes the event to the appropriate desk accessory as necessary.
If the mouse button was pressed while the cursor was in the content region of the desk accessory's window and the window is active, SystemClick sends the mouse-down event to the desk accessory to process. If the mouse-down event occurred in the content region of the window and the window is inactive, SystemClick makes it the active window. It does this by sending your application an activate event to deactivate its front window and directing an event to the desk accessory to activate its window.
If the mouse button was pressed while the cursor was in the drag region or go-away region, SystemClick calls the Window Manager function DragWindow (DragWindow) or TrackGoAway (TrackGoAway) , as appropriate. If TrackGoAway reports that the user closed the desk accessory, SystemClick sends a close message to the desk accessory.
See "The Event Record" for a description of the fields in the event record.
In a multiple-application environment, the WaitNextEvent function WaitNextEvent is responsible for giving time to each open desk accessory or driver to perform any periodic action. You should not call SystemTask if your application calls WaitNextEvent .
If your application calls GetNextEvent (GetNextEvent) , your application should call the SystemTask function.
pascal void SystemTask (void);
The SystemTask function gives time to each open desk accessory or driver to perform the periodic action defined for it. A desk accessory or device driver specifies how often the periodic action should occur, and SystemTask gives time to the desk accessory or device driver at the appropriate interval.
If your application calls GetNextEvent GetNextEvent , your application should call SystemTask at least every sixtieth of a second. This usually corresponds to calling SystemTask once each time through your event loop. If your application does a large amount of processing, you may need to call SystemTask more than once in your event loop.
The WaitNextEvent WaitNextEvent and GetNextEvent GetNextEvent functions call the SystemEvent function. In most cases your application should not call the SystemEvent function.
The SystemEvent function determines if a specific event should be handled by the application or the Operating System.
pascal Boolean SystemEvent (const EventRecord *theEvent);
SystemEvent returns false as its function result if the event should be handled by the application; otherwise, SystemEvent takes any appropriate actions and returns true .
For activate, update, mouse-up, and keyboard events (including keyboard equivalents of commands), SystemEvent checks to see whether the active window belongs to a desk accessory and whether that desk accessory can handle that type of event. If so, SystemEvent sends the event to the desk accessory and returns true . Otherwise, SystemEvent returns false .
For mouse-down events and null events, SystemEvent returns false .
For disk-inserted events, SystemEvent attempts to mount the disk using the PBMountVol function but returns false so that the application can perform further processing if necessary.
If the SEvtEnb global variable (a byte) contains 0, SystemEvent always returns false .
See "The Event Record" for a description of the fields in the event record. For a description of the PBMountVol function, see the chapter "File Manager" in Inside Macintosh: Files .
The Toolbox Event Manager calls the GetOSEvent function to retrieve low-level events stored in the Operating System event queue. In most cases, your application should not use this function.
pascal Boolean GetOSEvent (EventMask mask, EventRecord *theEvent);
The GetOSEvent function retrieves and removes an event from the Operating System event queue. GetOSEvent returns false as its function result if the event being returned is a null event; otherwise, GetOSEvent returns true . GetOSEvent does not intercept or respond to the event in any way. It also does not process Command-Shift- number key combinations or process any alarms set by the user through the Alarm Clock desk accessory.
You must set up register A0 with the address of an event record and register D0 with the event mask before invoking GetOSEvent . When GetOSEvent returns, register D0 indicates whether the returned event is a null event or an event other than a null event and the returned event is accessible through register A0.
|
0 if GetOSEvent returns any event other than a null event, or -1 if it returns a null event (low-order byte) |
|
See "The Event Record" for a description of the fields in the event record.
The Toolbox Event Manager uses the OSEventAvail function to retrieve an event from the Operating System event queue without removing it. In most cases your application does not need to use this function.
pascal Boolean OSEventAvail (EventMask mask, EventRecord *theEvent);
The OSEventAvail function retrieves an event from the Operating System event queue without removing it from the queue. The OSEventAvail function returns false as its function result if the event being returned is a null event; otherwise, OSEventAvail returns true .
OSEventAvail does not intercept or respond to the event in any way. It also does not process Command-Shift-number key combinations or process any alarms set by the user through the Alarm Clock desk accessory.
If the OSEventAvail function returns a low-level event from the Operating System event queue, the event will not be accessible later if, in the meantime, the event queue becomes full and the event is discarded from it; however, this is not a common occurrence.
You must set up register A0 with the address of an event record and register D0 with the event mask before invoking OSEventAvail . When OSEventAvail returns, register D0 indicates whether the returned event is a null event or some other event, and the returned event is accessible through register A0.
|
0 if OSEventAvail returns any event other than a null event, or -1 if it returns a null event (low-order byte) |
|
See "The Event Record" for a description of the fields in the event record
The SetEventMask function sets the system event mask of your application to the specified mask. Your application should not call the SetEventMask function to disable any event types from being posted. Use SetEventMask only to enable key-up events if your application needs to respond to key-up events.
pascal void SetEventMask (EventMask value);
The SetEventMask function sets the system event mask of your application according to the parameter value . The Operating System Event Manager posts only low-level events (other than update or activate events) corresponding to bits in the system event mask of the current process when posting events in the Operating System event queue. The system event mask of an application is initially set to post mouse-up, mouse-down, key-down, auto-key, and disk-inserted events into the Operating System event queue.
The Event Manager uses the GetEvQHdr function to get a pointer to the header of the Operating System event queue. In most cases, your application should not call the GetEvQHdr function.
pascal QHdrPtr GetEvQHdr (void);
The GetEvQHdr function returns a pointer to the header of the Operating System event queue.
The EventQueue system global variable contains the header of the event queue.
See "The Event Queue" for information on the structure of the Operating System event queue.